[WIP] Generate doc stubs for transplanted methods #2176
Conversation
|
It looks like this:
|
Codecov Report
@@ Coverage Diff @@
## develop #2176 +/- ##
========================================
Coverage 89.13% 89.13%
========================================
Files 143 143
Lines 17475 17475
Branches 2713 2713
========================================
Hits 15576 15576
Misses 1290 1290
Partials 609 609
Continue to review full report at Codecov.
|
The `transplant_stub.py` script introspects the groups and topology
attributes to write files in `documentation_pages/core` that contain the
documentation for the transplanted methods.
For the stubs to be picked up by sphinx, the docstring of the class to
document must contain
.. include:: XXX.txt
where "XXX" is the name of the class.
A stub contains a table of the methods, their short descriptions, and
what topology attribute they require.
Fixes #1845
The syntax is not supported in python 3.5
Locally, sphinx complains about citation duplicates. Though, travis complains about missing citations refering about the same citation.
|
That looks like a pretty pretty hacky but probably versatile solution. The only thing I don't like about it is that the function signatures are the ones of the original methods and not the transplanted ones. This will most likely confuse users. A rather ugly and certainly more tedious solution is to manually insert the transplanted methods in the Example for """
.. autoclass:: AtomGroup
:members:
:inherited-members:
.. autodata::
MDAnalysis.core.topologyattrs.Bonds.fragments
:annotation:
.. autofunction::
MDAnalysis.core.topologyattrs.Masses.center_of_mass(pbc=None, \
compound='group')
"""The empty |
|
Yes. It is a bit hacky... I was not expecting to have to manually call napoleon, nor did I expect to have to introspect the signatures. I should be able to treat the properties in a different way as I already have to detect them to grab their docstring. It is not sustainable to add the methods manually to the doc; the doc will lag behind very rapidly as we forget we have to do the manual operation. Though, it is possible to have the 'include' in the 'autoclass' rather than in the class docstrings. Would there be any benefit? Currently, the problem I have is that I do not know what to do with the references. If I keep the citations as is, sphinx complains about duplicates. If I remove them, then sphinx complains about missing citations. The only solution I can see is to introspect the modules doc to build a list of the citations, so I can remove only the reference that are already defined; though, I'd rather avoid doing that kind of book keeping. |
Can you give an example of what the problematic case looks like? |
|
Would it help if we decide that the only place where we have references is in documentation_pages/references.rst? We can add it to the Documentation Guide as a requirement. It would basically mean that within the docs you have to properly cite
Or perhaps we look into something like mcmtroffaes/sphinxcontrib-bibtex, at the cost of making doc writing a bit more convoluted. |
|
Superseded by #2418. |
The
transplant_stub.pyscript introspects the groups and topologyattributes to write files in
documentation_pages/corethat contain thedocumentation for the transplanted methods.
For the stubs to be picked up by sphinx, the docstring of the class to
document must contain
where "XXX" is the name of the class.
A stub contains a table of the methods, their short descriptions, and
what topology attribute they require.
Fixes #1845
PR Checklist